feat: add agentcore import command for starter toolkit migration#620
Merged
jesseturner21 merged 30 commits intoaws:mainfrom Mar 26, 2026
Merged
feat: add agentcore import command for starter toolkit migration#620jesseturner21 merged 30 commits intoaws:mainfrom
jesseturner21 merged 30 commits intoaws:mainfrom
Conversation
…containers
Two fixes:
1. Memory name prefix mismatch: CDK prefixes memory names with project
name (e.g. "myproject_Agent_mem") but import searched for unprefixed
YAML name. Added fallback lookup with project name prefix.
2. Container agents no longer trigger unnecessary Python venv setup
during import, since dependencies are installed inside the Docker image.
Constraint: CDK BasePrimitiveConstruct generates physicalName as ${projectName}_${name}
Rejected: Stripping prefix from CDK names | would break other CDK conventions
Confidence: high
Scope-risk: narrow
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
esbuild does not read tsconfig.json, so it defaults to classic JSX transform (React.createElement) while tsconfig specifies react-jsx (automatic). This produces 432 bare React.createElement calls in the bundle that reference a nonexistent React global, crashing all TUI commands (status, deploy, etc.) with "React is not defined". Constraint: esbuild ignores tsconfig jsx settings by default Rejected: Adding React as external | would require React in node_modules at runtime Confidence: high Scope-risk: narrow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The Starter Toolkit injects memory ID via BEDROCK_AGENTCORE_MEMORY_ID,
but CDK constructs use MEMORY_{NAME}_ID pattern. After import, agent
code still references the old env var, causing memory to silently fail.
Add a yellow warning during import telling users the correct env var
name to update in their agent code.
Constraint: CDK env var naming is controlled by AgentCoreMemory.getEnvVarName()
Rejected: Auto-rewrite agent source code | too fragile across frameworks
Confidence: high
Scope-risk: narrow
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The Starter Toolkit injects memory ID via BEDROCK_AGENTCORE_MEMORY_ID,
but CDK constructs use MEMORY_{NAME}_ID pattern. After import, agent
code still references the old env var, causing memory to silently fail.
Show a git-diff-style warning during import with red/green highlighting
so users see exactly what to change in their agent code.
Constraint: CDK env var naming is controlled by AgentCoreMemory.getEnvVarName()
Rejected: Auto-rewrite agent source code | too fragile across frameworks
Confidence: high
Scope-risk: narrow
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Import is a CLI-only command that requires --source flag and doesn't have a TUI screen. Remove it from the interactive command picker. Confidence: high Scope-risk: narrow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Import fails with "The specified bucket does not exist" when the AWS account hasn't been CDK-bootstrapped. The deploy command handles this via useCdkPreflight, but import bypasses that since it's CLI-only. Check bootstrap status after CDK synth and auto-bootstrap if needed, before disposing the toolkit wrapper. Tested on two unbootstrapped accounts (509471412906, 126432121770). Constraint: Must bootstrap before disposing toolkitWrapper since bootstrap requires it Rejected: Prompt user to manually run cdk bootstrap | poor UX for import flow Confidence: high Scope-risk: narrow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove unused waitUntilChangeSetCreateComplete import - Prefix unused assetHash with underscore - Add eslint-disable for necessary any cast in STS credentials - Remove unnecessary type assertion in test - Fix prettier formatting in multi-agent test Confidence: high Scope-risk: narrow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
OAuthCredentialProvider.discoveryUrl was made optional to support imported providers that already exist in Identity service. Update tests to match: - Schema test: expect success when discoveryUrl is omitted - Pre-deploy identity tests: add discoveryUrl to fixtures that test update and error paths (without it, the code now skips the provider) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…rAllMocks checkBootstrapNeeded and bootstrapEnvironment were created as inline vi.fn() inside the vi.mock factory. vi.clearAllMocks() in beforeEach wipes their mockResolvedValue, causing handleImport to fail in CI where test execution order differs from local runs. Hoist the mocks and configure them in setupCommonMocks like all other mock functions in the file. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When import fails during CDK build/synth or CloudFormation phases, the merged config (agentcore.json) was already written to disk. On retry, the import would detect existing agents and report false success without completing the CloudFormation import. This snapshots the original config before merging and restores it if any later phase fails. Constraint: Rollback only triggers after config is written (configWritten flag) Constraint: Snapshot must be a deep clone since projectSpec is mutated in-place Rejected: Deferred config write until after all phases | too invasive, changes control flow for all paths Confidence: high Scope-risk: narrow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
STM_ONLY memories incorrectly received a SEMANTIC strategy in the import flow, while the CLI create flow and starter toolkit both deploy STM_ONLY with zero strategies. This mismatch caused drift/errors during reconciliation. Constraint: Must match CLI create flow which maps shortTerm to strategies: [] Rejected: Keep SEMANTIC for STM_ONLY | causes reconciliation drift with deployed resources Confidence: high Scope-risk: narrow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
6 tasks
…it YAML Instead of warning users to manually recreate the gateway, the import pipeline now reads authorizer_configuration.customJWTAuthorizer from the starter toolkit YAML and writes authorizerType/authorizerConfiguration to agentcore.json so CDK handles it automatically. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Resolves npm ci failure caused by missing yaml@2.8.3 transitive dependency required by vitest/vite and lint-staged. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
tejaskash
approved these changes
Mar 26, 2026
Contributor
tejaskash
left a comment
There was a problem hiding this comment.
Looks good. Well-structured feature with strong test coverage.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a new
agentcore importCLI command that migrates existing Bedrock AgentCore Starter Toolkit projects into the agentcore-cli.Problem
Users who started with the Starter Toolkit have deployed agents, memories, and credentials via
.bedrock_agentcore.yaml. To adopt the CLI's richer feature set (TUI, multi-target deploys, evaluations, etc.), they need a migration path that preserves their existing AWS resources without downtime or re-creation.Solution
The
importcommand implements a 3-phase CloudFormation migration flow:Phase 1 (UPDATE): Deploys companion resources (IAM roles, policies) into a new or existing CloudFormation stack, filtering out primary AgentCore resources. Dangling
Ref/Fn::GetAttreferences to removed resources are replaced with"*"placeholders.Phase 2 (IMPORT): Uses CloudFormation's IMPORT change set mechanism to adopt pre-existing
AWS::BedrockAgentCore::RuntimeandAWS::BedrockAgentCore::Memoryresources into the stack, withDeletionPolicy: Retainto prevent accidental deletion.Phase 3 (user runs
agentcore deploy): Reconciles the full stack with the real synthesized CDK template, replacing placeholders and adding backDependsOnrelationships.Key capabilities
.bedrock_agentcore.yamlformat (handles agents, memories, credentials, VPC config, OAuth/API key providers, container vs CodeZip builds)agentcore.json, skipping duplicatesapp/<name>/, handles symlinks, excludes.venv/__pycache__/etc., copies Dockerfiles for container builds, fixes setuptools auto-discovery issuesagent_id: nullskip CloudFormation phases entirely (config-only merge)--targetfor multi-target projectsNew files
src/cli/commands/import/actions.tssrc/cli/commands/import/command.tssrc/cli/commands/import/constants.tssrc/cli/commands/import/index.tssrc/cli/commands/import/phase1-update.tssrc/cli/commands/import/phase2-import.tssrc/cli/commands/import/template-utils.tssrc/cli/commands/import/types.tssrc/cli/commands/import/yaml-parser.tsModified files
esbuild.config.mjsjsx: 'automatic'to match tsconfig'sreact-jsxsrc/cli/cli.tssrc/cli/operations/deploy/pre-deploy-identity.tssrc/cli/tui/utils/commands.tsimporttoHIDDEN_FROM_TUIsrc/schema/schemas/agentcore-project.tsdiscoveryUrloptional in OAuthCredentialSchemaRelated Issue
Closes #
Documentation PR
Type of Change
Testing
How have you tested the change?
npm run test:unitandnpm run test:integnpm run typechecknpm run lintsrc/assets/, I rannpm run test:update-snapshotsand committed the updated snapshotsUnit tests added (8 test files, ~200 tests)
container-agent-import.test.tsidempotency.test.tsimport-memory.test.tsimport-no-deploy.test.tsmerge-logic.test.tsmulti-agent.test.tstest1-no-memory-agent.test.tsvpc-import.test.tsManual testing
importdoes not appear in interactive command pickeragentcore import --source <yaml>works for: single agent, multi-agent, container builds, undeployed agents, re-import idempotencyChecklist
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.